<html>
<head>
<title>OSPFv2 Testsuite - Documentation</title>
<link rel="stylesheet" href="testsuite.css" type="text/css">
</head>
<body>
<br><hr>
<div align="center"> 
<a href="http://ssfnet.d-jacob.net">Home</a> | 
<a href="index.html">Up</a> | 
<a href="design.html">Previous</a> | 
<a href="testcases.html">Next</a>
</div>
<hr><br>
<h1>The SSF.OS.OSPFv2.test Package</h1>

Some of the testers for the OSPF test suite cannot be modeled using standard SSFNet components. 
Normally, SSFnet is configured statically -- that means, that the network configuration given 
in the DML file is maintained over the whole simulation. Wide parts of the OSPF specification 
deal with dynamic behavior of networks and how a router has to react on dynamic changes of the 
topology. To test those parts, this dynamic behavior has to be modeled in SSFNet. Five different 
classes of testers are needed to model all testers required by the OSPF test suite:

<ol>
<li>change a router's OSPF configuration at a given time during the simulation
<li>shut down and restart an OSPF router at a given time
<li>drop packets at given times to simulate link failures
<li>modify certain fields in packet headers
<li>specialized test behavior for particular tests, that may be dependent of the state of 
an adjacency
</ol>

All these are features specific to the OSPF test suite and cannot be implemented using 
standard SSFNet models. Therefore these behaviors are implemented in the 
<tt>SSF.OS.OSPFv2.test</tt> package. An overview of the classes provided by this package 
is given in Table 1.<p>

<div align="center">
<table border=1>
<tr bgcolor="#CCCCCC">
<td><b>Class</b></td>
<td><b>Description</b></td>
</tr>
<tr>
<td><tt>Configurator</tt></td>
<td>Dynamically updates the configuration of an OSPF session.</td>
</tr>
<tr>
<td><tt>ConfigUpdateMessage</tt></td>
<td>Protocol message used to send updates to OSPF.</td>
</tr>
<tr>
<td><tt>Reset</tt></td>
<td>Resets an OSPF session at a given time.</td>
<tr>
<td><tt>UnreliableIP</tt></td>
<td>Simulates links going down at a given time.</td>
</tr>
<tr>
<td><tt>IPwithErrorInjection</tt></td>
<td>Introduces simple errors into packets.</td>
</tr>
<tr>
<td><tt>PacketGenerator</tt></td>
<td>Models specialized complex testers for paticular tests.</td>
</tr>
<tr>
<td><tt>OSPFMonitor</tt></td>
<td>Dumps OSPF packets in <i>tcpdump</i> format.</td>
</tr>
<tr>
<td><tt>OSPFDumpPro</tt></td>
<td>Converts dumps from binary <i>tcpdump</i> format to text format.</td>
</tr>
<tr>
<td><tt>TOSDump</tt></td>
<td>Converts binary <i>tcpdump</i> files including the TOS fields.</td>
</tr>
<tr>
<td><tt>Logger</tt></td>
<td>Helper class to write output into the SSFnet logfile.</td>
</tr>
</table><br>
<b>Table 1</b> - Package overview
</div><p>

Looking closer at the <tt>UnreliableIP</tt>, <tt>IPwithErrorInjection</tt> and 
<tt>PacketGenerator</tt> classes, it becomes clear, that they all have to manipulate 
packets sent to or coming from an OSPF session. The simplest way to realize this in 
SSFnet is to put a <tt>ProtocolSession</tt> between IP and OSPF, which manipulates 
the packets accordingly, drops packets or sends new ones. In practice, putting the 
tester between OSPF and IP does not work. OSPF sends its packets directly to the protocol 
with name "ip". So, in order to manipulate packets coming from OSPF, the tester must be 
included in the protocol graph, using the name "ip". The IP session then has to use 
another name, e.g. "ip_original". The <tt>NIC</tt> class, which models the network 
interfaces also sends packets to the class with name "ip". If the tester uses this 
name, all packets are given directly to the tester. The IP session does not receive 
any packets at all.<p>

<div align="center"><img src="pictures/tester_graph.jpg" width=300 height=121><br>&nbsp;<br>
<b>Figure 4</b> - Putting testers into a protocol graph</div><p>
 
Because of this, the tester must additionally provide the functionality of IP. This can be 
realized by inheriance. The tester classes can simply extend the \texttt{IP} class, adding 
new functionality where necessary. To be able to use the functionality of different kinds 
of testers at the same time (e.g. link failures together with malformed hello packets), 
more complex tester classes again extend the simpler ones. This leads to the class hierarchy 
depicted in Figure 5.<p>

<div align="center"><img src="pictures/hierarchy.jpg" width=250 height=210><br>&nbsp;<br>
<b>Figure 4</b> - Class hierarchy for testers</div><p>

<h2>Unreliable Links</h2>

To model packet loss, the <tt>NIC</tt> class provides a facility to specify a percentage, 
at which incoming and outgoing packets are dropped. However, this feature does not allow 
a more accurate way of specifying link failures. The OSPF test suite requires a possibility, 
to specify accurately when and for how long a link fails. For the OSPF test suite it is 
sufficient to drop all incoming and outgoing packets to simulate a link failure. This 
functionality is implemented in the <tt>UnreliableIP</tt> class. To model link failures 
in DML, this class has to be used instead of IP in a router's protocol graph. In the 
configuration of the <tt>ProtocolSession</tt>, link failures can be modeled as follows:

<pre>
ProtocolSession [
    name ip
    use SSF.OS.OSPFv2.test.UnreliableIP
    fail [
        from      50.0
        until     100.0
        interface 0
    ]
]
</pre>

Everytimes <tt>UnreliableIP</tt> receives a packet in its <tt>push</tt> method, it checks 
if the current simulation time lies in a configured failure period. If this is true, the 
interface associated with this packet is determined. If this associated interface corresponds 
to the interface specified in the configuraton, the packet is dropped. Else, the packet is 
passed on to IP's <tt>push</tt> method.

<h2>Introducing Simple Errors</h2>

For some tests, OSPF packets which contain errors have to be generated. Simply creating 
an appropriate OSPF packet and sending it without behaving like an OSPF router would not 
do the job. E.g. when the router does not send Hello packets there will never be an adjacency 
and no database description packets are exchanged. So, the tester can never send erroneous 
database description packets. A solution for this problem is to wait for packets from the 
session, which are sent to a neighbor. These packets can now be modified accordingly before 
they are sent. For this, the <tt>IPwithErrorInjection</tt> class is put into a 
<tt>ProtocolGraph</tt> as a replacement for IP. To be able to use the features of the 
<tt>UnreliableIP</tt> class, <tt>IPwithErrorInjection</tt> is derived from this class. 
The configuration of the tester's protocol session now looks as follows:

<pre>
ProtocolSession [
    name ip
    use SSF.OS.OSPF.test.IPwithErrorInjection
    
    error [
        from      10.0
        until     20.0
        interface 0
        netmask   255.255.0.0
    ]
    error [
        from      20.0
        until     30.0
        interface 0
        bad_age   4000
    ]
    error [
        from      30.0
        until     40.0
        interface 0
        dd_mtu    2000
    ]
    fail [ ... ]
]
</pre>

There are three kinds of errors, which can be introduced into OSPF packets at given times on 
certain interfaces. The {\em netmask} error is used to change the netmask field of hello packets
to an arbitrary value. The MTU field of database description packets can be changed using the 
<i>dd_mtu</i> error. To change the age of LSAs in link state update packets, the <i>bad_age</i>
error can be used. When a packet is sent to <tt>IPwithErrorInjection</tt>, it is first checked, 
if the packet has to be manipulated. If yes, the packet is manipulated in the appropriate way. 
After that, it is sent to <tt>UnreliableIP</tt> for further processing. 


<h2>Complex Test Behavior</h2>

The <tt>IPwitErrorInjection</tt> class can be used to introduce simple errors into the OSPF 
protocol traffic. The class is not aware of the current state of an adjacency and simply 
introduces the same errors into all packets to which they are applicable. For some test 
scenarios a more advanced way was needed to manipulate OSPF packets or even introduce new 
ones. These features are implemented in the \texttt{PacketGenerator} class. The 
<tt>PacketGenerator</tt> keeps track of all OSPF packets. It maintains a data structure, 
where information about each neighbor and the associated adjacency is kept. Packets can 
now be originated or manipulated according to this information. The <tt>PacketGenerator</tt> 
is derived from the <tt>IPwithErrorInjection</tt> class, so this class's features are also 
available to the tester. The \texttt{PacketGenerator} can be configured from the DML file:

<pre>
ProtocolSession [
    name ip
    use SSF.OS.OSPF.test.PacketGenerator
    
    test[
        interface 0
        behavior  <name of test behavior>
    ]
    error[ ... ]
    
    fail[ ... ]
]
</pre>

Each test behavior is associated with an interface. The behavior of this interface is defined 
by a name, which corresponds to the name of the test case (see the 
<a href="http://www.iol.unh.edu">IOL test suite description</a>
for a list of test cases). Some test cases are subdivided into several independent test steps. 
Test behaviors for these test steps carry the name of the test case followed by a number, 
indicating the test step. Table 2 shows the test behaviors available in the 
<tt>PacketGenerator</tt> class. These behaviors are described in detail in 
the <a href="testcases.html">following Section</a>.<p>

<div align="center">
<table border=1>
<tr bgcolor="#CCCCCC">
<td><b>Test name</b></td>
<td><b>Test purpose / description</b></td>
</tr>
<tr>
<td>default</td>
<td>Normal OSPF behavior.</td>
</tr>
<tr>
<td>old_lsa_rcpt</td>
<td>Handling of the receipt of old LSAs (Test 2.6)</td>
</tr>
<tr>
<td>nbr_state_too_low</td>
<td>Correct handling of LSRequests from neighbors in a state &lt; EXCHANGE (Test 2.7)</td>
</tr>
<tr>
<td>dd_retransmit14</td>
<td>Retransmission of database description packets (Test 2.8)</td>
</tr>
<tr>
<td>event_seq_number_mismatch1-8</td>
<td>Verify the generation of the SequenceNumberMismatch event (Test 2.9)</td>
</tr>
<tr>
<td>lsa_request_retransmit1-2</td>
<td>Retransmission of LSRequest packets (Test 2.17)</td>
</tr>
<tr>
<td>event_bad_ls_req1-2</td>
<td>Correct handling of the BadLSReq event (Test 2.18)</td>
</tr>
<tr>
<td>remove_lsa_from_retransmission_list</td>
<td>Removing LSAs from the retransmission list when they are discarded from the database (Test 2.21)</td>
</tr>
<tr>
<td>ls_sequence_number_wrap</td>
<td>Correct behavior when sequence number is wrapping (Test 3.22)</td>
</tr>
</table><br>
<b>Table 2</b> - PacketGenerator behaviors</div><p>

<h2>Configuration Updates</h2>

Some test scenarios require dynamic updates of the OSPF configuration during a simulation. 
To configure such upates via the DML configuration, the <tt>Configurator</tt> class was 
implemented as a <tt>ProtocolSession</tt>, which can be included into the protocol graph 
of the router whose OSPF configuration must be updated. The DML configuration for the 
configurator looks as follows: 

<pre>
ProtocolSession [
    name configurator
    use SSF.OS.OSPFv2.test.Configurator
    
    update [
        time 100.0
        
        [...OSPF configuration...]
    ]
]
</pre>

Each update has a time associated with it and contains an OSPF DML configuration. This 
OSPF configuration may either be a complete configuration for all OSPF interfaces and areas 
or a partial configuration for a subset of interfaces or parameters. The parameters of the 
OSPF configuration which are not specified in the update remain unchanged.<p>

The <tt>Configurator</tt> adds each update to a list and starts a timer for each update, 
which fires at the specified time. Once the timer has fired, the update is removed from 
the list and the OSPF configuration is packaged into a <tt>ConfigUpdateMessage</tt>, which 
is derived from the <tt>ProtocolMessage</tt> class. This message is sent to the OSPF session 
by calling its <tt>push</tt> method. Support for the handling of <tt>ConfigUpdateMessages</tt> 
has been included in OSPF.<p>

The class <tt>com.renesys.raceway.DML.dmlConfig</tt> provides an interface to the DML 
configuration. Each DML configuration represents a configuration tree -- configuration 
updates for OSPF are a subtree of the global DML configuration. When sending updates to 
the OSPF session, these subtrees have to be copied into the <tt>ConfigUpdateMessage</tt>. 
The <tt>dmlConfig</tt> class is supposed to provide a method to copy a DML subtree to 
another place. But this method seems not to work correctly and delivers unpredictable 
results. Therefore the configuration is copied entry by entry.

<h2>Resetting OSPF</h2>

In some test cases, the OSPF session must be restarted during the simulation. To realize this, 
the <tt>Reset</tt> class was implemented which calls OSPF's <tt>stop</tt> and <tt>init</tt>
methods at times specified in the DML configuration. To be able to configure the <tt>Reset</tt>
class from DML, it was also derived from <tt>ProtocolSession</tt>. A typical DML configuration 
looks as follows:

<pre>
ProtocolSession [
    name reset
    use SSF.OS.OSPFv2.test.Reset
    
    stop  10.0
    start 20.0
    stop  30.0
    start 40.0
    ...
]
</pre>

<h2>Monitoring Packets</h2>

Whenever possible, the test cases should be implemented to be mostly independent from the 
particular OSPF implementation in order to be able to reuse the testsuite for other OSPF 
implementations. The implementation must be regarded as a black box. Tests are made by 
observing the inputs and outputs of the OSPF implementation. These inputs and outputs 
are typically IP packets, which must be logged. For this, SSFNet provides the possibility 
to define a \texttt{ProtocolMonitor} for an \texttt{IP} session. IP sends all packets to 
that monitor, before they are passed to the \texttt{NIC} or to a higher layer. 

The <tt>OSPFMonitor</tt> class implements such a monitor, which logs all OSPF packets 
passing through an IP session in a binary <i>tcpdump</i> format. A utility to convert these 
binary files into an ASCII format is implemented in the <tt>OSPFDumpPro</tt> class. The 
generated output corresponds to the format generated by <i>tcpdump</i>. To keep the 
generated logs small, not all IP headers are included in the converted files. One test 
requires the analysis of the IP TOS field. The <tt>TOSDump</tt> class can be used to generate 
a log file from the binary <i>tcpdump</i>, which contains only IP headers, including the 
TOS field.<p>

<br><hr>
<div align="center"> 
<a href="http://ssfnet.d-jacob.net">Home</a> | 
<a href="index.html">Up</a> | 
<a href="design.html">Previous</a> | 
<a href="testcases.html">Next</a>
</div>
<hr><br>

<i>Last update: 2002-02-05, Dirk Jacob (<a href="mailto:dirk@d-jacob.net">dirk@d-jacob.net</a>)</i>
</body>
</html>